home *** CD-ROM | disk | FTP | other *** search
/ Winzipper / Winzipper_ISO.iso / programming / oracle7 7.2 / DB / UTIL72 / DBMSJOB.SQL < prev    next >
Encoding:
Text File  |  1995-05-09  |  7.6 KB  |  165 lines
  1. rem 
  2. rem $Header: dbmsjob.sql 7020100.1 94/09/23 22:14:06 cli Generic<base> $ 
  3. rem 
  4. Rem  Copyright (c) 1992 by Oracle Corporation 
  5. Rem    NAME
  6. Rem      dbmsjob.sql - DBMS JOB queue interface
  7. Rem    DESCRIPTION
  8. Rem      Interface for the job queue
  9. Rem    RETURNS
  10. Rem 
  11. Rem    NOTES
  12. Rem      The job queue
  13. Rem      (1) Runs user-defined routines from background processes
  14. Rem          (or directly in the user's process)
  15. Rem      (2) Runs the jobs at user defined times 
  16. Rem          (or reasonably soon afterwards)
  17. Rem      (3) Runs a given job repeatedly at user defined intervals
  18. Rem          (or just once, then the job deletes itself)
  19. Rem      (4) Runs the jobs in the same environment they were submitted in
  20. Rem          (except with the user's default roles and privileges)
  21. Rem      (5) Reports errors, and does exponential backoff.
  22. Rem      (6) Allows the user to identify and administer these jobs. 
  23. Rem
  24. Rem      DBMS_JOB and DBMS_IJOB are the only interface for manipulating jobs.
  25. Rem      Queries against the catalog should be used for examining jobs.
  26. Rem      The catalog view dba_jobs and dba_jobs_running are in catjobq.sql.
  27. Rem      Out of all these routines, only dbms_job.run and dbms_ijob.run have
  28. Rem        implicit commits.
  29. Rem
  30. Rem      There are no kernel priveleges associated with jobs.  The right
  31. Rem        to execute dbms_job or dbms_ijob takes their place.  dbms_job
  32. Rem        does not allow a user to touch any jobs but their own.
  33. Rem
  34. Rem      (1) See the parameter WHAT in the specification for dbms_job for a
  35. Rem          description of legal jobs.
  36. Rem          The background processes are specified by init.ora parameters,
  37. Rem          job_queue_processes=2   #two background processes
  38. Rem          job_queue_interval=60   #the processes wake up every 60 seconds
  39. Rem          job_queue_keep_connections=TRUE  #sleep, don't disconnect
  40. Rem      (2) See NEXT_DATE in the specification for dbms_job
  41. Rem      (3) See INTERVAL in the specification for dbms_job
  42. Rem      (4) All the parameters that can be set with ALTER SESSION are stored
  43. Rem          when a job is created (or when WHAT is changed), and they are
  44. Rem          restored when the job is run.  See the view dba_jobs.
  45. Rem      (5) When dbms_job.run() or dbms_ijob.run() encounters an error, the
  46. Rem          complete errorstack is dumped to a trace file and an alert file.
  47. Rem          If dbms_ijob.run() was used, the number of jobs that ran with
  48. Rem          errors is reported to the user.
  49. Rem      (6) Jobs are identified by job number.  Jobs can be exported and
  50. Rem          imported again, and the job number will remain the same.
  51. Rem
  52. Rem    MODIFIED   (MM/DD/YY)
  53. Rem     rjenkins   02/17/94 -  adding defaults
  54. Rem     rjenkins   02/07/94 -  many fixes
  55. Rem     adowning   02/02/94 -  split file into public / private binary files
  56. Rem     rjenkins   01/26/94 -  fix arguments to BROKEN
  57. Rem     rjenkins   01/13/94 -  adding dbms_ijob.bis
  58. Rem     rjenkins   12/20/93 -  support import/export
  59. Rem     rjenkins   12/20/93 -  Branch_for_patch
  60. Rem     rjenkins   12/17/93 -  Creation
  61.  
  62. REM  -----------------------------------------------------
  63. REM  dbms_job: job queue functions for public consumption
  64. REM  -----------------------------------------------------
  65.  
  66. CREATE OR REPLACE PACKAGE dbms_job IS
  67.  
  68.   -- Parameters are:
  69.   --
  70.   -- JOB is the number of the job being executed.
  71.   -- WHAT is the PL/SQL procedure to execute.
  72.   --   The job must always be a single call to a procedure.  The
  73.   --     routine may take any number of hardcoded parameters.  
  74.   --     Special parameter values recognized are:
  75.   --       job:       an in parameter, the number of the current job
  76.   --       next_date: in/out, the date of the next refresh
  77.   --       broken:    in/out, is the job broken.  The IN values is FALSE.
  78.   --   Always remember the trailing semicolon.
  79.   --   Some legal values of WHAT (assuming the routines exist) are
  80.   --     'myproc( ''10-JAN-82'', next_date, broken);'
  81.   --     'scott.emppackage.give_raise( ''JENKINS'', 30000.00);'
  82.   --     'dbms_job.remove( job);'
  83.   -- NEXT_DATE is the date at which the job will next be automatically run,
  84.   --   assuming there are background processes attempting to run it.
  85.   -- INTERVAL is a date function, evaluated immediately before the job starts
  86.   --   executing.  If the job completes successfully, this new date is placed
  87.   --   in NEXT_DATE.  INTERVAL is evaluated by plugging it into the statement
  88.   --     select INTERVAL into next_date from dual;
  89.   --   INTERVAL must evaluate to a time in the future.  Legal intervals include
  90.   --     'sysdate + 7'                    -- execute once a week
  91.   --     'NEXT_DAY(sysdate,''TUESDAY'')'  -- execute once every tuesday
  92.   --     'null'                           -- only execute once
  93.   --   If INTERVAL evaluates to null and a job completes successfully, then
  94.   --   the job is automatically deleted from the queue.
  95.  
  96.   PROCEDURE isubmit    ( job       IN  BINARY_INTEGER,
  97.                          what      IN  VARCHAR2,
  98.                          next_date IN  VARCHAR2,
  99.                          interval  IN  VARCHAR2 DEFAULT 'null',
  100.                          no_parse  IN  BOOLEAN DEFAULT FALSE );
  101.   -- Submit a new job with a given job number.
  102.  
  103.   PROCEDURE submit    ( job       OUT BINARY_INTEGER,
  104.                         what      IN  VARCHAR2,
  105.                         next_date IN  DATE DEFAULT sysdate,
  106.                         interval  IN  VARCHAR2 DEFAULT 'null',
  107.                         no_parse  IN  BOOLEAN DEFAULT FALSE);
  108.   -- Submit a new job.  Chooses JOB from the sequence sys.jobseq.
  109.   -- For example,
  110.   --   variable x number;
  111.   --   execute dbms_job.submit(:x,'pack.proc(''arg1'')',sysdate,'sysdate+1');
  112.  
  113.   PROCEDURE remove    ( job       IN  BINARY_INTEGER );
  114.   -- Remove an existing job from the job queue.
  115.   -- This currently does not stop a running job.
  116.   --   execute dbms_job.remove(14144);
  117.  
  118.   PROCEDURE change    ( job       IN  BINARY_INTEGER,
  119.                         what      IN  VARCHAR2,
  120.                         next_date IN  DATE,
  121.                         interval  IN  VARCHAR2);
  122.   -- Change any of the the user-settable fields in a job
  123.   -- If what, next_date, or interval is null, leave that value as-is.
  124.   --   execute dbms_job.change( 14144, null, null, 'sysdate+3');
  125.  
  126.   PROCEDURE what      ( job       IN  BINARY_INTEGER,
  127.                         what      IN  VARCHAR2 );
  128.   -- Change what an existing job does, and replace its environment
  129.  
  130.   PROCEDURE next_date ( job       IN  BINARY_INTEGER,
  131.                         next_date IN  DATE     );
  132.   -- Change when an existing job will next execute
  133.  
  134.   PROCEDURE interval  ( job       IN  BINARY_INTEGER,
  135.                         interval  IN  VARCHAR2 );
  136.   -- Change how often a job executes
  137.  
  138.   PROCEDURE broken    ( job       IN  BINARY_INTEGER,
  139.                         broken    IN  BOOLEAN,
  140.                         next_date IN  DATE DEFAULT SYSDATE );
  141.   --  Set the broken flag.  Broken jobs are never run.
  142.  
  143.   PROCEDURE run       ( job       IN  BINARY_INTEGER);
  144.   --  Run job JOB now.  Run it even if it is broken.
  145.   --  Running the job will recompute next_date, see view user_jobs.
  146.   --    execute dbms_job.run(14144);
  147.   --  Warning: this will reinitialize the current session's packages
  148.  
  149.   PROCEDURE user_export ( job    IN     BINARY_INTEGER,
  150.                           mycall IN OUT VARCHAR2);
  151.   --  Produce the text of a call to recreate the given job
  152.  
  153.   PROCEDURE check_privs ( job IN BINARY_INTEGER );
  154.  
  155. END;
  156. /
  157.  
  158.  
  159. DROP PUBLIC SYNONYM dbms_job
  160. /
  161. CREATE PUBLIC SYNONYM dbms_job FOR dbms_job
  162. /
  163. GRANT EXECUTE ON dbms_job TO PUBLIC WITH GRANT OPTION
  164. /
  165.